RuleManagerApp Installation

Please note that this document is still under revision, so slight changes still might occur before the final version of this draft.

Introduction

COMPASS 6 provides a new web application for editing the COMPASS rules. Since version 6.2 it is called RuleManagerApp and requires the RuleManagerService as backend component. This document covers the installation and configuration of RuleManagerApp.

RuleManagerApp - Installation and Configuration

RuleManagerApp: is a pure web application based on Angular. It requires a running instance of RuleManagerService (see RuleManagerApp 6.2) and may be deployed in an HTTP webserver, but it’s also possible to deploy it in the same server environment as the backend.

RuleManagerService can be secured either via OAuth2 using COMPASS' AuthorizationServer (see Authorization-Server; configuration springAuthorization) or via your own Keycloak - installation (see Keycloak documentation; configuration keycloakAuthorization). The configuration of RuleManagerService to work with Keycloak is described here: RuleManagerService).

It is also possible not secure the RuleManagerService: its configuration allows the values dbAuthorization and noAuthorization with the following effect on the RuleManagerApp:

In case of dbAuthorization the RuleManagerApp will ask for a user/password login. This combination is sent to the backend for confirmation. If successful, this user is allowed to start working without further authorization.

In the case of noAuthorization, the RuleManagerApp will allow work with the default user defined by the property disabledAuthUser. The RuleManagerService is not protected.

A schematic representation of the secured architecture looks as follows:

We recommend using the most recent version of Google Chrome to view RuleManagerApp.

Note that, server-wide, it is not possible to access RuleManager with more than one user at the same time. After a certain period of inactivity, a timeout logs a user out automatically and a re-login is necessary to continue their work.

File Structure

File / Directory	Description
index.html	The only HTML file. Every URL path must resolve to this file. When it’s opened, all styles and Angular runtime files (.js)* are loaded and Angular resolves the URL. Note that the "base href" needs to be set in this file if you use Tomcat.
main.js (and others)	Minified Angular files. Do not change the content of these!
config/appConfig.json	The configuration file (see below.)

File / Directory

Description

index.html

The only HTML file. Every URL path must resolve to this file. When it’s opened, all styles and Angular runtime files (*.js) are loaded and Angular resolves the URL. Note that the "base href" needs to be set in this file if you use Tomcat.

main.js (and others)

Minified Angular files. Do not change the content of these!

config/appConfig.json

The configuration file (see below.)

Installation and configuration

This document describes the installation of the server side of the RuleManager on an Apache Tomcat web server/web container version 9 as an example:

Install your servlet container (i.e. Apache Tomcat) and start it. Make sure that the welcome page of Apache Tomcat appears on the installed machine at localhost:8080/index.html.

Port 8080 is the default port of the Apache Tomcat installation. It may differ for your installation.

The file RuleManagerApp.war is an archive that may be unpacked if deployed in a conventional HTTP server. If a servlet container such as Apache Tomcat is used, the WAR file can be copied to the webapps folder as-is, and is then accessible via localhost:8080/RuleManagerApp:.

If you would like to access RuleManagerApp: under a different URL:

Rename the war file and
Edit the base-href in index.html within that war file: <base href="/[New name]/">

Configuration

The RuleManagerApp>'s configuration is located in appConfig.json, which looks like this:

{
  "RuleManagerServiceUrl": "http://localhost:8080/RuleManagerService/",
  "CompassAuthorizationBase": "/CompassAuthorization/",
  "disabledAuthUser": "UW_POS",
  "KeycloakAuthorization": {
      "baseHref": "/RuleManagerApp/",
      "moduleConfig": {
        "clientId": "rulemanager-client",
        "requireHttps": true,
        "issuer": "https://www.example-auth.genre.com/realms/Compass",
        "sessionCheckIntervall": 15000,
        "showDebugInformation": false
      }
  },
  "conditionDeletionConfirmation": true,
  "onlySB1Editor": true
}

The properties are described here:

Property Name	Type	Mandatory	Default	Description
"RuleManagerServiceUrl"	String	yes	"http://localhost:8080/RuleManagerService"	URL to the RuleManager Service.
"CompassAuthorizationBase"	String	only for springAuthorization	"/CompassAuthorization/"	URL to CompassAuthorization.
"disabledAuthUser"	String	only for noAuthorization	"UW_POS"	The user which is used for logging changes to the database if auth is deactivated.
"baseHref"	String	only for Keycloak	"/RuleManagerApp/"	The name of the app. Keycloak uses this as the redirect URI.
"silentTokenRefreshEnabled"	true \| false	no	(omitted)	If true, will disable the token refresh dialog and instead auto-refresh every time.
"moduleConfig"	JSON	only for Keycloak		Parameters for setting up Keycloak. See table below.
"conditionDeletionConfirmation"	true \| false	yes	true	If true, shows a confirm dialog before deleting a rule in DB editor.
"onlySB1Editor"	true \| false	yes	true	If true, disables experimental SB2 editor.

Property Name

Type

Mandatory

Default

Description

"RuleManagerServiceUrl"

String

yes

"http://localhost:8080/RuleManagerService"

URL to the RuleManager Service.

"CompassAuthorizationBase"

String

only for springAuthorization

"/CompassAuthorization/"

URL to CompassAuthorization.

"disabledAuthUser"

String

only for noAuthorization

"UW_POS"

The user which is used for logging changes to the database if auth is deactivated.

"baseHref"

String

only for Keycloak

"/RuleManagerApp/"

The name of the app. Keycloak uses this as the redirect URI.

"silentTokenRefreshEnabled"

true | false

(omitted)

If true, will disable the token refresh dialog and instead auto-refresh every time.

"moduleConfig"

JSON

only for Keycloak

Parameters for setting up Keycloak. See table below.

"conditionDeletionConfirmation"

true | false

yes

true

If true, shows a confirm dialog before deleting a rule in DB editor.

"onlySB1Editor"

true | false

yes

true

If true, disables experimental SB2 editor.

Keycloak (openid)

Note that all properties below are mandatory within "moduleConfig".

Property Name	Type	Default	Description
"clientId"	string	"caseviewer-client"	The id Keycloak uses to identify received tokens by.
"requireHttps"	true \| false	true	True if https should be used for Keycloak.
"issuer"	String	"http://localhost:8080/realms/Compass"	URL to the Keycloak realm.
"sessionCheckIntervall"	Number (positive)	15000	How often the token should be checked for validity. Number in milliseconds. See notes below
"showDebugInformation"	true \| false	false	Show debug information from Keycloak.

Property Name

Type

Default

Description

"clientId"

string

"caseviewer-client"

The id Keycloak uses to identify received tokens by.

"requireHttps"

true | false

true

True if https should be used for Keycloak.

"issuer"

String

"http://localhost:8080/realms/Compass"

URL to the Keycloak realm.

"sessionCheckIntervall"

Number (positive)

15000

How often the token should be checked for validity. Number in milliseconds. See notes below

"showDebugInformation"

true | false

false

Show debug information from Keycloak.

Notes on sessionCheckIntervall

The two ls in 'intervall' is a "required typo" due to the module being used.
The interval does NOT specify the session / login duration of a user, this can be configured in the Keycloak administration console itself.

A comprehensive overview about configuring RuleManagerService with property parameter can be found here.